home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / jack / ringbuffer.h < prev    next >
C/C++ Source or Header  |  2005-12-20  |  8KB  |  237 lines
  1. /*
  2.     Copyright (C) 2000 Paul Davis
  3.     Copyright (C) 2003 Rohan Drape
  4.     
  5.     This program is free software; you can redistribute it and/or modify
  6.     it under the terms of the GNU Lesser General Public License as published by
  7.     the Free Software Foundation; either version 2.1 of the License, or
  8.     (at your option) any later version.
  9.     
  10.     This program is distributed in the hope that it will be useful,
  11.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13.     GNU Lesser General Public License for more details.
  14.     
  15.     You should have received a copy of the GNU Lesser General Public License
  16.     along with this program; if not, write to the Free Software 
  17.     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  18.  
  19.     $Id: ringbuffer.h,v 1.6 2004/07/08 17:21:03 joq Exp $
  20. */
  21.  
  22. #ifndef _RINGBUFFER_H
  23. #define _RINGBUFFER_H
  24.  
  25. #ifdef __cplusplus
  26. extern "C" {
  27. #endif
  28.  
  29. #include <sys/types.h>
  30.  
  31. /** @file ringbuffer.h
  32.  *
  33.  * A set of library functions to make lock-free ringbuffers available
  34.  * to JACK clients.  The `capture_client.c' (in the example_clients
  35.  * directory) is a fully functioning user of this API.
  36.  *
  37.  * The key attribute of a ringbuffer is that it can be safely accessed
  38.  * by two threads simultaneously -- one reading from the buffer and
  39.  * the other writing to it -- without using any synchronization or
  40.  * mutual exclusion primitives.  For this to work correctly, there can
  41.  * only be a single reader and a single writer thread.  Their
  42.  * identities cannot be interchanged.
  43.  */
  44.  
  45. typedef struct  
  46. {
  47.   char  *buf;
  48.   size_t len;
  49. } 
  50. jack_ringbuffer_data_t ;
  51.  
  52. typedef struct
  53. {
  54.   char         *buf;
  55.   volatile size_t write_ptr;
  56.   volatile size_t read_ptr;
  57.   size_t      size;
  58.   size_t      size_mask;
  59.   int          mlocked;
  60. } 
  61. jack_ringbuffer_t ;
  62.  
  63. /**
  64.  * Allocates a ringbuffer data structure of a specified size. The
  65.  * caller must arrange for a call to jack_ringbuffer_free() to release
  66.  * the memory associated with the ringbuffer.
  67.  *
  68.  * @param sz the ringbuffer size in bytes.
  69.  *
  70.  * @return a pointer to a new jack_ringbuffer_t, if successful; NULL
  71.  * otherwise.
  72.  */
  73. jack_ringbuffer_t *jack_ringbuffer_create(size_t sz);
  74.  
  75. /**
  76.  * Frees the ringbuffer data structure allocated by an earlier call to
  77.  * jack_ringbuffer_create().
  78.  *
  79.  * @param rb a pointer to the ringbuffer structure.
  80.  */
  81. void jack_ringbuffer_free(jack_ringbuffer_t *rb);
  82.  
  83. /**
  84.  * Fill a data structure with a description of the current readable
  85.  * data held in the ringbuffer.  This description is returned in a two
  86.  * element array of jack_ringbuffer_data_t.  Two elements are needed
  87.  * because the data to be read may be split across the end of the
  88.  * ringbuffer.
  89.  *
  90.  * The first element will always contain a valid @a len field, which
  91.  * may be zero or greater.  If the @a len field is non-zero, then data
  92.  * can be read in a contiguous fashion using the address given in the
  93.  * corresponding @a buf field.
  94.  *
  95.  * If the second element has a non-zero @a len field, then a second
  96.  * contiguous stretch of data can be read from the address given in
  97.  * its corresponding @a buf field.
  98.  *
  99.  * @param rb a pointer to the ringbuffer structure.
  100.  * @param vec a pointer to a 2 element array of jack_ringbuffer_data_t.
  101.  *
  102.  */
  103. void jack_ringbuffer_get_read_vector(const jack_ringbuffer_t *rb,
  104.                      jack_ringbuffer_data_t *vec);
  105.  
  106. /**
  107.  * Fill a data structure with a description of the current writable
  108.  * space in the ringbuffer.  The description is returned in a two
  109.  * element array of jack_ringbuffer_data_t.  Two elements are needed
  110.  * because the space available for writing may be split across the end
  111.  * of the ringbuffer.
  112.  *
  113.  * The first element will always contain a valid @a len field, which
  114.  * may be zero or greater.  If the @a len field is non-zero, then data
  115.  * can be written in a contiguous fashion using the address given in
  116.  * the corresponding @a buf field.
  117.  *
  118.  * If the second element has a non-zero @a len field, then a second
  119.  * contiguous stretch of data can be written to the address given in
  120.  * the corresponding @a buf field.
  121.  *
  122.  * @param rb a pointer to the ringbuffer structure.
  123.  * @param vec a pointer to a 2 element array of jack_ringbuffer_data_t.
  124.  */
  125. void jack_ringbuffer_get_write_vector(const jack_ringbuffer_t *rb,
  126.                       jack_ringbuffer_data_t *vec);
  127.  
  128. /**
  129.  * Read data from the ringbuffer.
  130.  *
  131.  * @param rb a pointer to the ringbuffer structure.
  132.  * @param dest a pointer to a buffer where data read from the
  133.  * ringbuffer will go.
  134.  * @param cnt the number of bytes to read.
  135.  *
  136.  * @return the number of bytes read, which may range from 0 to cnt.
  137.  */
  138. size_t jack_ringbuffer_read(jack_ringbuffer_t *rb, char *dest, size_t cnt);
  139.  
  140. /**
  141.  * Read data from the ringbuffer. Opposed to jack_ringbuffer_read()
  142.  * this function does not move the read pointer. Thus it's
  143.  * a convenient way to inspect data in the ringbuffer in a
  144.  * continous fashion. The price is that the data is copied
  145.  * into a user provided buffer. For "raw" non-copy inspection
  146.  * of the data in the ringbuffer use jack_ringbuffer_get_read_vector().
  147.  *
  148.  * @param rb a pointer to the ringbuffer structure.
  149.  * @param dest a pointer to a buffer where data read from the
  150.  * ringbuffer will go.
  151.  * @param cnt the number of bytes to read.
  152.  *
  153.  * @return the number of bytes read, which may range from 0 to cnt.
  154.  */
  155. size_t jack_ringbuffer_peek(jack_ringbuffer_t *rb, char *dest, size_t cnt);
  156.  
  157. /**
  158.  * Advance the read pointer.
  159.  *
  160.  * After data have been read from the ringbuffer using the pointers
  161.  * returned by jack_ringbuffer_get_read_vector(), use this function to
  162.  * advance the buffer pointers, making that space available for future
  163.  * write operations.
  164.  *
  165.  * @param rb a pointer to the ringbuffer structure.
  166.  * @param cnt the number of bytes read.
  167.  */
  168. void jack_ringbuffer_read_advance(jack_ringbuffer_t *rb, size_t cnt);
  169.  
  170. /**
  171.  * Return the number of bytes available for reading.
  172.  *
  173.  * @param rb a pointer to the ringbuffer structure.
  174.  *
  175.  * @return the number of bytes available to read.
  176.  */
  177. size_t jack_ringbuffer_read_space(const jack_ringbuffer_t *rb);
  178.  
  179. /**
  180.  * Lock a ringbuffer data block into memory.
  181.  *
  182.  * Uses the mlock() system call.  This is not a realtime operation.
  183.  *
  184.  * @param rb a pointer to the ringbuffer structure.
  185.  */
  186. int jack_ringbuffer_mlock(jack_ringbuffer_t *rb);
  187.  
  188. /**
  189.  * Reset the read and write pointers, making an empty buffer.
  190.  *
  191.  * This is not thread safe.
  192.  *
  193.  * @param rb a pointer to the ringbuffer structure.
  194.  */
  195. void jack_ringbuffer_reset(jack_ringbuffer_t *rb);
  196.  
  197. /**
  198.  * Write data into the ringbuffer.
  199.  *
  200.  * @param rb a pointer to the ringbuffer structure.
  201.  * @param src a pointer to the data to be written to the ringbuffer.
  202.  * @param cnt the number of bytes to write.
  203.  *
  204.  * @return the number of bytes write, which may range from 0 to cnt
  205.  */
  206. size_t jack_ringbuffer_write(jack_ringbuffer_t *rb, const char *src,
  207.                  size_t cnt);
  208.  
  209. /**
  210.  * Advance the write pointer.
  211.  *
  212.  * After data have been written the ringbuffer using the pointers
  213.  * returned by jack_ringbuffer_get_write_vector(), use this function
  214.  * to advance the buffer pointer, making the data available for future
  215.  * read operations.
  216.  *
  217.  * @param rb a pointer to the ringbuffer structure.
  218.  * @param cnt the number of bytes written.
  219.  */
  220. void jack_ringbuffer_write_advance(jack_ringbuffer_t *rb, size_t cnt);
  221.  
  222. /**
  223.  * Return the number of bytes available for writing.
  224.  *
  225.  * @param rb a pointer to the ringbuffer structure.
  226.  *
  227.  * @return the amount of free space (in bytes) available for writing.
  228.  */
  229. size_t jack_ringbuffer_write_space(const jack_ringbuffer_t *rb);
  230.  
  231.  
  232. #ifdef __cplusplus
  233. }
  234. #endif
  235.  
  236. #endif
  237.